<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>xmake</title>
  <link rel="icon" href="/assets/img/favicon.ico">
  <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
  <meta name="description" content="Description">
  <meta name="viewport" content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0">
  <link href="//cdn.jsdelivr.net/npm/github-markdown-css@4.0.0/github-markdown.min.css" rel="stylesheet">
  <style>
	.markdown-body {
		box-sizing: border-box;
		min-width: 200px;
		max-width: 980px;
		margin: 0 auto;
		padding: 45px;
	}

	@media (max-width: 767px) {
		.markdown-body {
			padding: 15px;
		}
	}
  </style>
</head>
<body>
<article class="markdown-body">
<h4>This is a mirror page, please see the original page: </h4><a href="https://xmake.io/#/manual/custom_rule">https://xmake.io/#/manual/custom_rule</a>
</br>
    <script async type="text/javascript" src="//cdn.carbonads.com/carbon.js?serve=CE7I52QU&placement=xmakeio" id="_carbonads_js"></script>
<style>
#carbonads {
  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen-Sans, Ubuntu,
  Cantarell, "Helvetica Neue", Helvetica, Arial, sans-serif;
}

#carbonads {
  display: flex;
  max-width: 330px;
  background-color: hsl(0, 0%, 98%);
  box-shadow: 0 1px 4px 1px hsla(0, 0%, 0%, .1);
}

#carbonads a {
  color: inherit;
  text-decoration: none;
}

#carbonads a:hover {
  color: inherit;
}

#carbonads span {
  position: relative;
  display: block;
  overflow: hidden;
}

#carbonads .carbon-wrap {
  display: flex;
}

.carbon-img {
  display: block;
  margin: 0;
  line-height: 1;
}

.carbon-img img {
  display: block;
}

.carbon-text {
  font-size: 13px;
  padding: 10px;
  line-height: 1.5;
  text-align: left;
}

.carbon-poweredby {
  display: block;
  padding: 8px 10px;
  background: repeating-linear-gradient(-45deg, transparent, transparent 5px, hsla(0, 0%, 0%, .025) 5px, hsla(0, 0%, 0%, .025) 10px) hsla(203, 11%, 95%, .4);
  text-align: center;
  text-transform: uppercase;
  letter-spacing: .5px;
  font-weight: 600;
  font-size: 9px;
  line-height: 1;
}
</style>
    <p>After the 2.2.1 release, xmake not only natively supports the construction of multi-language files, but also allows users to implement complex unknown file builds by custom building rules.</p>
<p>Custom build rules can have a set of file extensions associated to them using <code>set_extensions</code>.<br>Once these extensions are associated to the rule a later call to <code>add_files</code> will automatically use this custom rule.<br>Here is an example rule that will use Pandoc to convert markdown files added to a build target in to HTML files:</p>
<pre><code class="lang-lua">-- Define a build rule for a markdown file
rule("markdown")
    set_extensions(".md", ".markdown")
    on_build_file(function (target, sourcefile, opt)
        import("core.project.depend")
        import("utils.progress") -- it only for v2.5.9, we need use print to show progress below v2.5.8

        -- make sure build directory exists
        os.mkdir(target:targetdir())

        -- replace .md with .html
        local targetfile = path.join(target:targetdir(), path.basename(sourcefile) .. ".html")

        -- only rebuild the file if its changed since last run
        depend.on_changed(function ()
            -- call pandoc to make a standalone html file from a markdown file
            os.vrunv(&#39;pandoc&#39;, {"-s", "-f", "markdown", "-t", "html", "-o", targetfile, sourcefile})
            progress.show(opt.progress, "${color.build.object}markdown %s", sourcefile)
        end, {files = sourcefile})
    end)

target("test")
    set_kind("object")

    -- make the test target support the construction rules of the markdown file
    add_rules("markdown")

    -- adding a markdown file to build
    add_files("src/*.md")
    add_files("src/*.markdown")
</code></pre>
<p>Note that in xmake a rule is responsible for checking when targets are out of date and informing the user of ongoing progress.</p>
<p>There is also an alternative to <code>on_build_file</code> in the form of <code>on_build_files</code> which allows you to process the entire set of files in one function call.</p>
<p>A second form called <code>on_buildcmd_file</code> and <code>on_buildcmd_files</code> is instead declarative; rather than running arbitrary Lua to build a target it runs Lua to learn how those targets are built.<br>The advantage to <code>buildcmd</code> is that those rules can be exported to makefiles which do not require xmake at all in order to run.</p>
<p>We can use buildcmd to simplify it further, like this:</p>
<pre><code class="lang-lua">-- Define a build rule for a markdown file
rule("markdown")
    set_extensions(".md", ".markdown")
    on_buildcmd_file(function (target, batchcmds, sourcefile, opt)

        -- make sure build directory exists
        batchcmds:mkdir(target:targetdir())

        -- replace .md with .html
        local targetfile = path.join(target:targetdir(), path.basename(sourcefile) .. ".html")

        -- call pandoc to make a standalone html file from a markdown file
        batchcmds:vrunv(&#39;pandoc&#39;, {"-s", "-f", "markdown", "-t", "html", "-o", targetfile, sourcefile})
        batchcmds:show_progress(opt.progress, "${color.build.object}markdown %s", sourcefile)

        -- only rebuild the file if its changed since last run
        batchcmds:add_depfiles(sourcefile)
    end)

target("test")
    set_kind("object")

    -- make the test target support the construction rules of the markdown file
    add_rules("markdown")

    -- adding a markdown file to build
    add_files("src/*.md")
    add_files("src/*.markdown")
</code></pre>
<p>Files can be assigned to a specific rule regardless of their file extension. You do this by setting the <code>rule</code> custom property when adding the file like in the following example:</p>
<pre><code class="lang-lua">target("test")
    add_files("src/test/*.md.in", {rule = "markdown"})
</code></pre>
<p>A target can be superimposed to apply multiple rules to more customize its own build behavior, and even support different build environments.</p>
<p>!> Rules specified by <code>add_files("*.md", {rule = "markdown"})</code>, with a higher priority than the rule set by <code>add_rules("markdown")</code>.</p>
<h3 id="builtinrules">Built-in rules</h3>
<p>sinceAfter the 2.2.1 release, xmake provides some built-in rules to simplify the daily xmake.lua description and support for some common build environments.</p>
<p>We can view the complete list of built-in rules by running the following command:</p>
<pre><code class="lang-bash">$ xmake show -l rules
</code></pre>
<h4 id="modedebug">mode.debug</h4>
<p>Add the configuration rules for the debug compilation mode for the current project xmake.lua, for example:</p>
<pre><code class="lang-lua">add_rules("mode.debug")
</code></pre>
<p>Equivalent to:</p>
<pre><code class="lang-lua">if is_mode("debug") then
    set_symbols("debug")
    set_optimize("none")
end
</code></pre>
<p>We can switch to this compilation mode by <code>xmake f -m debug</code>.</p>
<h4 id="moderelease">mode.release</h4>
<p>Add the configuration rules for the release compilation mode for the current project xmake.lua, for example:</p>
<pre><code class="lang-lua">add_rules("mode.release")
</code></pre>
<p>Equivalent to:</p>
<pre><code class="lang-lua">if is_mode("release") then
    set_symbols("hidden")
    set_optimize("fastest")
    set_strip("all")
end
</code></pre>
<p>We can switch to this compilation mode by <code>xmake f -m release</code>.</p>
<h4 id="modereleasedbg">mode.releasedbg</h4>
<p>Add the configuration rules for the releasedbg compilation mode for the current project xmake.lua, for example:</p>
<pre><code class="lang-lua">add_rules("mode.releasedbg")
</code></pre>
<p>!> Compared with the release mode, this mode will also enable additional debugging symbols, which is usually very useful.</p>
<p>Equivalent to:</p>
<pre><code class="lang-lua">if is_mode("releasedbg") then
    set_symbols("debug")
    set_optimize("fastest")
    set_strip("all")
end
</code></pre>
<p>We can switch to this compilation mode by <code>xmake f -m releasedbg</code>.</p>
<h4 id="modeminsizerel">mode.minsizerel</h4>
<p>Add the configuration rules for the minsizerel compilation mode for the current project xmake.lua, for example:</p>
<pre><code class="lang-lua">add_rules("mode.minsizerel")
</code></pre>
<p>!> Compared with the release mode, this mode is more inclined to the minimum code compilation optimization, rather than speed priority.</p>
<p>相当于：</p>
<pre><code class="lang-lua">if is_mode("minsizerel") then
    set_symbols("hidden")
    set_optimize("smallest")
    set_strip("all")
end
</code></pre>
<p>We can switch to this compilation mode by <code>xmake f -m minsizerel</code>.</p>
<h4 id="modecheck">mode.check</h4>
<p>Add the check compilation mode configuration rules for the current project xmake.lua, generally used for memory detection, for example:</p>
<pre><code class="lang-lua">add_rules("mode.check")
</code></pre>
<p>Equivalent to:</p>
<pre><code class="lang-lua">if is_mode("check") then
    set_symbols("debug")
    set_optimize("none")
    add_cxflags("-fsanitize=address", "-ftrapv")
    add_mxflags("-fsanitize=address", "-ftrapv")
    add_ldflags("-fsanitize=address")
end
</code></pre>
<p>We can switch to this compilation mode by <code>xmake f -m check</code>.</p>
<h4 id="modeprofile">mode.profile</h4>
<p>Add configuration rules for the profile compilation mode for the current project xmake.lua, which is generally used for performance analysis, for example:</p>
<pre><code class="lang-lua">add_rules("mode.profile")
</code></pre>
<p>Equivalent to:</p>
<pre><code class="lang-lua">if is_mode("profile") then
    set_symbols("debug")
    add_cxflags("-pg")
    add_ldflags("-pg")
end
</code></pre>
<p>We can switch to this compilation mode by <code>xmake f -m profile</code>.</p>
<h4 id="modecoverage">mode.coverage</h4>
<p>Add the configuration rules for the coverage compilation mode for the current project xmake.lua, which is generally used for coverage analysis, for example:</p>
<pre><code class="lang-lua">add_rules("mode.coverage")
</code></pre>
<p>Equivalent to:</p>
<pre><code class="lang-lua">if is_mode("coverage") then
    add_cxflags("--coverage")
    add_mxflags("--coverage")
    add_ldflags("--coverage")
end
</code></pre>
<p>We can switch to this compilation mode by <code>xmake f -m coverage</code>.</p>
<h4 id="modevalgrind">mode.valgrind</h4>
<p>This mode provides valgrind memory analysis and detection support.</p>
<pre><code class="lang-lua">add_rules("mode.valgrind")
</code></pre>
<p>We can switch to this compilation mode by: <code>xmake f -m valgrind</code>.</p>
<h4 id="modeasan">mode.asan</h4>
<p>This mode provides AddressSanitizer memory analysis and detection support.</p>
<pre><code class="lang-lua">add_rules("mode.asan")
</code></pre>
<p>We can switch to this compilation mode by: <code>xmake f -m asan</code>.</p>
<h4 id="modetsan">mode.tsan</h4>
<p>This mode provides ThreadSanitizer memory analysis and detection support.</p>
<pre><code class="lang-lua">add_rules("mode.tsan")
</code></pre>
<p>We can switch to this compilation mode by: <code>xmake f -m tsan</code>.</p>
<h4 id="modelsan">mode.lsan</h4>
<p>This mode provides LeakSanitizer memory analysis and detection support.</p>
<pre><code class="lang-lua">add_rules("mode.lsan")
</code></pre>
<p>We can switch to this compilation mode by: <code>xmake f -m lsan</code>.</p>
<h4 id="modeubsan">mode.ubsan</h4>
<p>This mode provides UndefinedBehaviorSanitizer memory analysis and detection support.</p>
<pre><code class="lang-lua">add_rules("mode.ubsan")
</code></pre>
<p>We can switch to this compilation mode by: <code>xmake f -m ubsan</code>.</p>
<h4 id="qtstatic">qt.static</h4>
<p>A static library program used to compile and generate Qt environments:</p>
<pre><code class="lang-lua">target("test")
    add_rules("qt.static")
    add_files("src/*.cpp")
    add_frameworks("QtNetwork", "QtGui")
</code></pre>
<h4 id="qtshared">qt.shared</h4>
<p>Dynamic library program for compiling and generating Qt environment:</p>
<pre><code class="lang-lua">target("test")
    add_rules("qt.shared")
    add_files("src/*.cpp")
    add_frameworks("QtNetwork", "QtGui")
</code></pre>
<h4 id="qtconsole">qt.console</h4>
<p>A console program for compiling and generating a Qt environment:</p>
<pre><code class="lang-lua">target("test")
    add_rules("qt.console")
    add_files("src/*.cpp")
</code></pre>
<h4 id="qtquickapp">qt.quickapp</h4>
<p>Quick(qml) ui application for compiling and generating Qt environment.</p>
<pre><code class="lang-lua">target("test")
    add_rules("qt.quickapp")
    add_files("src/*.cpp")
    add_files("src/qml.qrc")
</code></pre>
<h4 id="qtquickapp_static">qt.quickapp_static</h4>
<p>Quick(qml) ui application (statically linked version) for compiling and generating Qt environment.</p>
<p>!> Need to switch to static library version Qt SDK</p>
<pre><code class="lang-lua">target("test")
    add_rules("qt.quickapp_static")
    add_files("src/*.cpp")
    add_files("src/qml.qrc")
</code></pre>
<h4 id="qtwidgetapp">qt.widgetapp</h4>
<p>Used to compile Qt Widgets (ui/moc) applications</p>
<pre><code class="lang-lua">target("test")
    add_rules("qt.widgetapp")
    add_files("src/*.cpp")
    add_files("src/mainwindow.ui")
    add_files("src/mainwindow.h") -- add meta header files with Q_OBJECT
</code></pre>
<h4 id="qtwidgetapp_static">qt.widgetapp_static</h4>
<p>Used to compile Qt Widgets (ui/moc) applications (static library version)</p>
<p>!> Need to switch to static library version Qt SDK</p>
<pre><code class="lang-lua">target("test")
    add_rules("qt.widgetapp_static")
    add_files("src/*.cpp")
    add_files("src/mainwindow.ui")
    add_files("src/mainwindow.h") -- add meta header files with Q_OBJECT
</code></pre>
<p>For more descriptions of Qt, see: <a href="https://github.com/xmake-io/xmake/issues/160">#160</a></p>
<h4 id="xcodebundle">xcode.bundle</h4>
<p>Used to compile and generate ios/macos bundle program</p>
<pre><code class="lang-lua">target("test")
     add_rules("xcode.bundle")
     add_files("src/*.m")
     add_files("src/Info.plist")
</code></pre>
<h4 id="xcodeframework">xcode.framework</h4>
<p>Used to compile and generate ios/macos framework program</p>
<pre><code class="lang-lua">target("test")
     add_rules("xcode.framework")
     add_files("src/*.m")
     add_files("src/Info.plist")
</code></pre>
<h4 id="xcodeapplication">xcode.application</h4>
<p>Used to compile and generate ios/macos applications</p>
<pre><code class="lang-lua">target("test")
     add_rules("xcode.application")
     add_files("src/*.m", "src/**.storyboard", "src/*.xcassets")
     add_files("src/Info.plist")
</code></pre>
<h4 id="wdkenvkmdf">wdk.env.kmdf</h4>
<p>Application of the compilation environment setting of kmdf under WDK, need to cooperate with: <code>wdk.[driver|binary|static|shared]</code> and other rules to use.</p>
<h4 id="wdkenvumdf">wdk.env.umdf</h4>
<p>Application of the umdf compiler environment settings under WDK, you need to cooperate with: <code>wdk.[driver|binary|static|shared]</code> and other rules to use.</p>
<h4 id="wdkenvwdm">wdk.env.wdm</h4>
<p>Application wdm compiler environment settings under WDK, need to cooperate with: <code>wdk.[driver|binary|static|shared]</code> and other rules to use.</p>
<h4 id="wdkdriver">wdk.driver</h4>
<p>Compile and generate drivers based on the WDK environment under Windows. Currently, only the WDK10 environment is supported.</p>
<p>Note: need to cooperate: <code>wdk.env.[umdf|kmdf|wdm]</code>Environmental rules are used.</p>
<pre><code class="lang-lua">-- add target
target("echo")

    -- add rules
    add_rules("wdk.driver", "wdk.env.kmdf")

    -- add files
    add_files("driver/*.c")
    add_files("driver/*.inx")

    -- add includedirs
    add_includedirs("exe")
</code></pre>
<h4 id="wdkbinary">wdk.binary</h4>
<p>Compile and generate executable programs based on WDK environment under Windows. Currently, only WDK10 environment is supported.</p>
<p>Note: It is necessary to cooperate with: environment rules such as <code>wdk.env.[umdf|kmdf|wdm]</code>.</p>
<pre><code class="lang-lua">-- add target
target("app")

    -- add rules
    add_rules("wdk.binary", "wdk.env.umdf")

    -- add files
    add_files("exe/*.cpp")
</code></pre>
<h4 id="wdkstatic">wdk.static</h4>
<p>Compile and generate static library programs based on WDK environment under Windows. Currently, only WDK10 environment is supported.</p>
<p>Note: It is necessary to cooperate with: environment rules such as <code>wdk.env.[umdf|kmdf|wdm]</code>.</p>
<pre><code class="lang-lua">target("nonpnp")

    -- add rules
    add_rules("wdk.static", "wdk.env.kmdf")

    -- add flags for rule: wdk.tracewpp
    add_values("wdk.tracewpp.flags", "-func:TraceEvents(LEVEL,FLAGS,MSG,...)", "-func:Hexdump((LEVEL,FLAGS,MSG,...))")

    -- add files
    add_files("driver/*.c", {rule = "wdk.tracewpp"})
</code></pre>
<h4 id="wdkshared">wdk.shared</h4>
<p>Compile and generate dynamic library programs based on WDK environment under Windows. Currently, only WDK10 environment is supported.</p>
<p>Note: It is necessary to cooperate with: environment rules such as <code>wdk.env.[umdf|kmdf|wdm]</code>.</p>
<pre><code class="lang-lua">target("nonpnp")

    -- add rules
    add_rules("wdk.shared", "wdk.env.wdm")

    -- add flags for rule: wdk.tracewpp
    add_values("wdk.tracewpp.flags", "-func:TraceEvents(LEVEL,FLAGS,MSG,...)", "-func:Hexdump((LEVEL,FLAGS,MSG,...))")

    -- add files
    add_files("driver/*.c", {rule = "wdk.tracewpp"})
</code></pre>
<h4 id="wdktracewpp">wdk.tracewpp</h4>
<p>Used to enable tracewpp to preprocess source files:</p>
<pre><code class="lang-lua">target("nonpnp")

    -- add rules
    add_rules("wdk.driver", "wdk.env.kmdf")

    -- add flags for rule: wdk.tracewpp
    add_values("wdk.tracewpp.flags", "-func:TraceEvents(LEVEL,FLAGS,MSG,...)", "-func:Hexdump((LEVEL,FLAGS,MSG,...))")

    -- add files
    add_files("driver/*.c", {rule = "wdk.tracewpp"})
    add_files("driver/*.rc")
</code></pre>
<p>For more information on WDK rules, see: <a href="https://github.com/xmake-io/xmake/issues/159">#159</a></p>
<h4 id="winsdkapplication">win.sdk.application</h4>
<p>Compile and generate the winsdk application.</p>
<pre><code class="lang-lua">-- add rules
add_rules("mode.debug", "mode.release")

-- define target
target("usbview")

    -- windows application
    add_rules("win.sdk.application")

    -- add files
    add_files("*.c", "*.rc")
    add_files("xmlhelper.cpp", {rule = "win.sdk.dotnet"})
</code></pre>
<h4 id="wdksdkdotnet">wdk.sdk.dotnet</h4>
<p>Used to specify certain c++ source files to be compiled as c++.net.</p>
<pre><code class="lang-lua">add_files("xmlhelper.cpp", {rule = "win.sdk.dotnet"})
</code></pre>
<p>For more information on WDK rules, see: <a href="https://github.com/xmake-io/xmake/issues/159">#159</a></p>
<h4 id="pluginvsxmakeautoupdate">plugin.vsxmake.autoupdate</h4>
<p>We can use this rule to automatically update the VS project file (when each build is completed) in the VS project generated by <code>xmake project -k vsxmake</code>.</p>
<pre><code class="lang-lua">add_rules("plugin.vsxmake.autoupdate")
target("test")
     set_kind("binary")
     add_files("src/*.c")
</code></pre>
<h4 id="utilssymbolsexport_all">utils.symbols.export_all</h4>
<p>Provided in v2.5.2 and above, we can use it to automatically export all dynamic library symbols. Currently, only the symbol export of windows dll target programs is supported, even if there is no export interface through <code>__declspec(dllexport)</code> in the code.<br>xmake will also automatically export all c interface symbols (there are too many c++ class library symbols, so I haven&#39;t exported them yet).</p>
<pre><code class="lang-lua">add_rules("mode.release", "mode.debug")

target("foo")
     set_kind("shared")
     add_files("src/foo.c")
     add_rules("utils.symbols.export_all")

target("test")
     set_kind("binary")
     add_deps("foo")
     add_files("src/main.c")
</code></pre>
<p>Related issue <a href="https://github.com/xmake-io/xmake/issues/1123">#1123</a></p>
<h4 id="utilsinstallcmake_importfiles">utils.install.cmake_importfiles</h4>
<p>We can use this rule to export the .cmake file when installing the target library file for the library import and search of other cmake projects.</p>
<h4 id="utilsinstallpkgconfig_importfiles">utils.install.pkgconfig_importfiles</h4>
<p>We can use this rule to export the pkgconfig/.pc file when installing the target target library file for library import and search for other projects.</p>
<h4 id="utilsbin2c">utils.bin2c</h4>
<p>This rule can be used in versions above v2.5.7 to introduce some binary files into the project, and see them as c/c++ header files for developers to use to obtain the data of these files.</p>
<p>For example, we can embed some png/jpg resource files into the code in the project.</p>
<pre><code class="lang-lua">target("console")
    set_kind("binary")
    add_rules("utils.bin2c", {extensions = {".png", ".jpg"}})
    add_files("src/*.c")
    add_files("res/*.png", "res/*.jpg")
</code></pre>
<p>!> The setting of extensions is optional, the default extension is .bin</p>
<p>Then, we can import and use it through <code>#include "filename.png.h"</code>, xmake will automatically generate the corresponding header file for you, and add the corresponding search directory.</p>
<pre><code class="lang-c">static unsigned char g_png_data[] = {
    #include "image.png.h"
};

int main(int argc, char** argv)
{
    printf("image.png: %s, size: %d\n", g_png_data, sizeof(g_png_data));
    return 0;
}
</code></pre>
<p>The content of the generated header file is similar:</p>
<pre><code class="lang-console">cat build/.gens/test/macosx/x86_64/release/rules/c++/bin2c/image.png.h
  0x68, 0x65, 0x6C, 0x6C, 0x6F, 0x20, 0x78, 0x6D, 0x61, 0x6B, 0x65, 0x21, 0x0A, 0x00
</code></pre>
<h4 id="utilsglsl2spv">utils.glsl2spv</h4>
<p>This rule can be used in v2.6.1 and above. Import glsl shader files such as <code>*.vert/*.frag</code> into the project, and then realize automatic compilation to generate <code>*.spv</code> files.</p>
<p>In addition, we also support binary embedding spv file data in the form of C/C++ header file, which is convenient for program use.</p>
<h5 id="compileandgeneratespvfile">Compile and generate spv file</h5>
<p>xmake will automatically call glslangValidator or glslc to compile shaders to generate .spv files, and then output them to the specified <code>{outputdir = "build"}</code> directory.</p>
<pre><code class="lang-lua">add_rules("mode.debug", "mode.release")

add_requires("glslang", {configs = {binaryonly = true}})

target("test")
    set_kind("binary")
    add_rules("utils.glsl2spv", {outputdir = "build"})
    add_files("src/*.c")
    add_files("src/*.vert", "src/*.frag")
    add_packages("glslang")
</code></pre>
<p>Note that the <code>add_packages("glslang")</code> here is mainly used to import and bind the glslangValidator in the glslang package to ensure that xmake can always use it.</p>
<p>Of course, if you have already installed it on your own system, you don’t need to bind this package additionally, but I still recommend adding it.</p>
<h5 id="compileandgenerateccheaderfiles">Compile and generate c/c++ header files</h5>
<p>We can also use the bin2c module internally to generate the corresponding binary header file from the compiled spv file, which is convenient for direct import in user code. We only need to enable <code>{bin2c = true}</code>. :w</p>
<pre><code class="lang-lua">add_rules("mode.debug", "mode.release")

add_requires("glslang", {configs = {binaryonly = true}})

target("test")
    set_kind("binary")
    add_rules("utils.glsl2spv", {bin2c = true})
    add_files("src/*.c")
    add_files("src/*.vert", "src/*.frag")
    add_packages("glslang")
</code></pre>
<p>Then we can introduce in the code like this:</p>
<pre><code class="lang-c">static unsigned char g_test_vert_spv_data[] = {
    #include "test.vert.spv.h"
};

static unsigned char g_test_frag_spv_data[] = {
    #include "test.frag.spv.h"
};
</code></pre>
<p>Similar to the usage of bin2c rules, see the complete example: <a href="https://github.com/xmake-io/xmake/tree/master/tests/projects/other/glsl2spv">glsl2spv example</a></p>
<h3 id="rule">rule</h3>
<h4 id="definingrules">Defining rules</h4>
<pre><code class="lang-lua">rule("markdown")
    set_extensions(".md", ".markdown")
    on_build_file(function (target, sourcefile, opt)
        os.cp(sourcefile, path.join(target:targetdir(), path.basename(sourcefile) .. ".html"))
    end)
</code></pre>
<h3 id="ruleadd_imports">rule:add_imports</h3>
<h4 id="addimportedmodulesforallcustomscripts">Add imported modules for all custom scripts</h4>
<p>For usage and description, please see: <a href="#targetadd_imports">target:add_imports</a>, the usage is the same.</p>
<h3 id="ruleset_extensions">rule:set_extensions</h3>
<h4 id="settingthefileextensiontypesupportedbytherule">Setting the file extension type supported by the rule</h4>
<p>Apply rules to files with these suffixes by setting the supported extension file types, for example:</p>
<pre><code class="lang-lua">-- Define a build rule for a markdown file
rule("markdown")
    set_extensions(".md", ".markdown")
    on_build_file(function (target, sourcefile, opt)
        os.cp(sourcefile, path.join(target:targetdir(), path.basename(sourcefile) .. ".html"))
    end)

target("test")
    set_kind("binary")

    -- Make the test target support the construction rules of the markdown file
    add_rules("markdown")

    -- Adding a markdown file to build
    add_files("src/*.md")
    add_files("src/*.markdown")
</code></pre>
<h3 id="ruleon_load">rule:on_load</h3>
<h4 id="customloadscript">Custom load script</h4>
<p>The load script used to implement the custom rules will be executed when the target is loaded. You can customize some target configurations in it, for example:</p>
<pre><code class="lang-lua">rule("test")
    on_load(function (target)
        target:add("defines", "-DTEST")
    end)
</code></pre>
<h3 id="ruleon_link">rule:on_link</h3>
<h4 id="customlinkscript">Custom link script</h4>
<p>The link script used to implement the custom rules overrides the default link behavior of the applied target, for example:</p>
<pre><code class="lang-lua">rule("test")
    on_link(function (target)
    end)
</code></pre>
<h3 id="ruleon_build">rule:on_build</h3>
<h4 id="customcompilationscript">Custom compilation script</h4>
<p>The build script used to implement the custom rules overrides the default build behavior of the target being applied, for example:</p>
<pre><code class="lang-lua">rule("markdown")
    on_build(function (target)
    end)
</code></pre>
<h3 id="ruleon_clean">rule:on_clean</h3>
<h4 id="customcleanupscript">Custom cleanup script</h4>
<p>The cleanup script used to implement the custom rules will override the default cleanup behavior of the applied target, for example:</p>
<pre><code class="lang-lua">rule("markdown")
    on_clean(function (target)
        -- remove sourcefile.html
    end)
</code></pre>
<h3 id="ruleon_package">rule:on_package</h3>
<h4 id="custompackagingscript">Custom packaging script</h4>
<p>A packaging script for implementing custom rules that overrides the default packaging behavior of the target being applied, for example:</p>
<pre><code class="lang-lua">rule("markdown")
    on_package(function (target)
        -- package sourcefile.html
    end)
</code></pre>
<h3 id="ruleon_install">rule:on_install</h3>
<h4 id="custominstallationscript">Custom installation script</h4>
<p>An installation script for implementing custom rules that overrides the default installation behavior of the target being applied, for example:</p>
<pre><code class="lang-lua">rule("markdown")
    on_install(function (target)
    end)
</code></pre>
<h3 id="ruleon_uninstall">rule:on_uninstall</h3>
<h4 id="customuninstallscript">Custom Uninstall Script</h4>
<p>An uninstall script for implementing custom rules that overrides the default uninstall behavior of the target being applied, for example:</p>
<pre><code class="lang-lua">rule("markdown")
    on_uninstall(function (target)
    end)
</code></pre>
<h3 id="ruleon_build_file">rule:on_build_file</h3>
<h4 id="customizingthebuildscripttoprocessonesourcefileatatime">Customizing the build script to process one source file at a time</h4>
<pre><code class="lang-lua">rule("markdown")
    on_build_file(function (target, sourcefile, opt)
        print("%%%d: %s", opt.progress, sourcefile)
    end)
</code></pre>
<p>The third parameter opt is an optional parameter, which is used to obtain some information state during the compilation process. For example, opt.progress is the compilation progress of the current period.</p>
<h3 id="ruleon_buildcmd_file">rule:on_buildcmd_file</h3>
<h4 id="custombatchcompilescriptprocessonesourcefileatatime">Custom batch compile script, process one source file at a time</h4>
<p>This is a new interface added in version 2.5.2. The script inside will not directly construct the source file, but will construct a batch command line task through the batchcmds object.<br>When xmake actually executes the build, it executes these commands once.</p>
<p>This is very useful for project generator plugins such as <code>xmake project</code>, because third-party project files generated by the generator do not support the execution of built-in scripts such as <code>on_build_files</code>.</p>
<p>But the final result of <code>on_buildcmd_files</code> construction is a batch of original cmd command lines, which can be directly executed as custom commands for other project files.</p>
<p>In addition, compared to <code>on_build_files</code>, it also simplifies the implementation of compiling extension files, is more readable and easy to configure, and is more user-friendly.</p>
<pre><code class="lang-lua">rule("foo")
    set_extensions(".xxx")
    on_buildcmd_file(function (target, batchcmds, sourcefile, opt)
        batchcmds:vrunv("gcc", {"-o", objectfile, "-c", sourcefile})
        batchcmds:add_depfiles("/xxxxx/dependfile.h", ...)
        -- batchcmds:add_depvalues(...)
        -- batchcmds:set_depmtime(os.mtime(...))
        -- batchcmds:set_depcache("xxxx.d")
    end)
</code></pre>
<p>In addition to <code>batchcmds:vrunv</code>, we also support some other batch commands, such as:</p>
<pre><code class="lang-lua">batchcmds:show("hello %s", "xmake")
batchcmds:vrunv("gcc", {"-o", objectfile, "-c", sourcefile}, {envs = {LD_LIBRARY_PATH="/xxx"}})
batchcmds:mkdir("/xxx") - and cp, mv, rm, ln ..
batchcmds:compile(sourcefile_cx, objectfile, {configs = {includedirs = sourcefile_dir, languages ​​= (sourcekind == "cxx" and "c++11")}})
batchcmds:link(objectfiles, targetfile, {configs = {linkdirs = ""}})
</code></pre>
<p>At the same time, we also simplify the configuration of dependency execution in it. The following is a complete example:</p>
<pre><code class="lang-lua">rule("lex")
    set_extensions(".l", ".ll")
    on_buildcmd_file(function (target, batchcmds, sourcefile_lex, opt)

        - imports
        import("lib.detect.find_tool")

        - get lex
        local lex = assert(find_tool("flex") or find_tool("lex"), "lex not found!")

        - get c/c++ source file for lex
        local extension = path.extension(sourcefile_lex)
        local sourcefile_cx = path.join(target:autogendir(), "rules", "lex_yacc", path.basename(sourcefile_lex) .. (extension == ".ll" and ".cpp" or ".c"))

        - add objectfile
        local objectfile = target:objectfile(sourcefile_cx)
        table.insert(target:objectfiles(), objectfile)

        - add commands
        batchcmds:show_progress(opt.progress, "${color.build.object}compiling.lex %s", sourcefile_lex)
        batchcmds:mkdir(path.directory(sourcefile_cx))
        batchcmds:vrunv(lex.program, {"-o", sourcefile_cx, sourcefile_lex})
        batchcmds:compile(sourcefile_cx, objectfile)

        - add deps
        batchcmds:add_depfiles(sourcefile_lex)
        batchcmds:set_depmtime(os.mtime(objectfile))
        batchcmds:set_depcache(target:dependfile(objectfile))
    end)
</code></pre>
<p>For a detailed description and background of this, see: <a href="https://github.com/xmake-io/xmake/issues/1246">issue 1246</a></p>
<h3 id="ruleon_build_files">rule:on_build_files</h3>
<h4 id="customizingthebuildscripttoprocessmultiplesourcefilesatonce">Customizing the build script to process multiple source files at once</h4>
<p>Most of the custom build rules, each time processing a single file, output a target file, for example: a.c => a.o</p>
<p>However, in some cases, we need to enter multiple source files together to build an object file, for example: a.c b.c d.c => x.o</p>
<p>For this situation, we can achieve this by customizing this script:</p>
<pre><code class="lang-lua">rule("markdown")
    on_build_files(function (target, sourcebatch, opt)
        -- build some source files
        for _, sourcefile in ipairs(sourcebatch.sourcefiles) do
            -- ...
        end
    end)
</code></pre>
<h3 id="ruleon_buildcmd_files">rule:on_buildcmd_files</h3>
<h4 id="customizebatchcompilingscriptprocessmultiplesourcefilesatonce">Customize batch compiling script, process multiple source files at once</h4>
<p>For a detailed description of this, see: <a href="#ruleon_buildcmd_file">rule:on_buildcmd_file</a></p>
<pre><code class="lang-lua">rule("foo")
     set_extensions(".xxx")
     on_buildcmd_files(function (target, batchcmds, sourcebatch, opt)
         for _, sourcefile in ipairs(sourcebatch.sourcefiles) do
             batchcmds:vrunv("gcc", {"-o", objectfile, "-c", sourcefile})
         end
     end)
</code></pre>
<h3 id="rulebefore_link">rule:before_link</h3>
<h4 id="customprelinkscript">Custom pre-link script</h4>
<p>Execution scripts used to implement custom target links, for example:</p>
<pre><code class="lang-lua">rule("test")
    before_link(function (target)
    end)
</code></pre>
<h3 id="rulebefore_build">rule:before_build</h3>
<h4 id="customprecompilationscript">Custom pre-compilation script</h4>
<p>Used to implement the execution script before the custom target is built, for example:</p>
<pre><code class="lang-lua">rule("markdown")
    before_build(function (target)
    end)
</code></pre>
<h3 id="rulebefore_clean">rule:before_clean</h3>
<h4 id="customprecleanupscript">Custom pre-cleanup script</h4>
<p>Used to implement the execution script before the custom target cleanup, for example:</p>
<pre><code class="lang-lua">rule("markdown")
    before_clean(function (target)
    end)
</code></pre>
<h3 id="rulebefore_package">rule:before_package</h3>
<h4 id="customtheprepackagescript">Custom the pre-package script</h4>
<p>Used to implement the execution script before the custom target is packaged, for example:</p>
<pre><code class="lang-lua">rule("markdown")
    before_package(function (target)
    end)
</code></pre>
<h3 id="rulebefore_install">rule:before_install</h3>
<h4 id="custompreinstallationscript">Custom pre-installation script</h4>
<p>Used to implement the execution script before the custom target installation, for example:</p>
<pre><code class="lang-lua">rule("markdown")
    before_install(function (target)
    end)
</code></pre>
<h3 id="rulebefore_uninstall">rule:before_uninstall</h3>
<h4 id="custompreuninstallscript">Custom pre-uninstall script</h4>
<p>Used to implement the execution script before the custom target is uninstalled, for example:</p>
<pre><code class="lang-lua">rule("markdown")
    before_uninstall(function (target)
    end)
</code></pre>
<h3 id="rulebefore_build_file">rule:before_build_file</h3>
<h4 id="customprecompilationscripttoprocessonesourcefileatatime">Custom pre-compilation script to process one source file at a time</h4>
<p>Similar to <a href="#ruleon_build_file">rule:on_build_file</a>, but the timing of this interface is called before compiling a source file.<br>Generally used to preprocess some source files before compiling.</p>
<h3 id="rulebefore_buildcmd_file">rule:before_buildcmd_file</h3>
<h4 id="customizetheprecompilationbatchscriptprocessonesourcefileatatime">Customize the pre-compilation batch script, process one source file at a time</h4>
<p>Similar to the usage of <a href="#ruleon_buildcmd_file">rule:on_buildcmd_file</a>, but the time when this interface is called is before compiling a certain source file.<br>It is generally used to pre-process certain source files before compilation.</p>
<h3 id="rulebefore_build_files">rule:before_build_files</h3>
<h4 id="customizeprecompilationscriptstoprocessmultiplesourcefilesatonce">Customize pre-compilation scripts to process multiple source files at once</h4>
<p>Similar to the usage of <a href="#ruleon_build_files">rule:on_build_files</a>, but the time when this interface is called is before compiling some source files,<br>It is generally used to pre-process certain source files before compilation.</p>
<h3 id="rulebefore_buildcmd_files">rule:before_buildcmd_files</h3>
<h4 id="customizetheprecompilationbatchscripttoprocessmultiplesourcefilesatonce">Customize the pre-compilation batch script to process multiple source files at once</h4>
<p>Similar to the usage of <a href="#ruleon_buildcmd_files">rule:on_buildcmd_files</a>, but the time when this interface is called is before compiling some source files,<br>It is generally used to pre-process certain source files before compilation.</p>
<h3 id="ruleafter_link">rule:after_link</h3>
<h4 id="custompostlinkingscript">Custom post-linking script</h4>
<p>The execution script used to implement the custom target link is similar to <a href="#ruleafter_link">rule:after_link</a>.</p>
<h3 id="ruleafter_build">rule:after_build</h3>
<h4 id="custompostcompilationscript">Custom post-compilation script</h4>
<p>The execution script used to implement the custom target build is similar to <a href="#rulebefore_build">rule:before_build</a>.</p>
<h3 id="ruleafter_clean">rule:after_clean</h3>
<h4 id="custompostcleaningscript">Custom post-cleaning script</h4>
<p>The execution script used to implement the custom target cleanup is similar to <a href="#rulebefore_clean">rule:before_clean</a>.</p>
<h3 id="ruleafter_package">rule:after_package</h3>
<h4 id="custompostpackagingscript">Custom post-packaging script</h4>
<p>The execution script used to implement the custom target package is similar to <a href="#rulebefore_package">rule:before_package</a>.</p>
<h3 id="ruleafter_install">rule:after_install</h3>
<h4 id="custompostinstallationscript">Custom post-installation script</h4>
<p>The execution script used to implement the custom target installation is similar to <a href="#rulebefore_install">rule:before_install</a>.</p>
<h3 id="ruleafter_uninstall">rule:after_uninstall</h3>
<h4 id="custompostuninstallationscript">Custom post-uninstallation Script</h4>
<p>The execution script used to implement the custom target uninstallation is similar to <a href="#rulebefore_uninstall">rule:before_uninstall</a>.</p>
<h3 id="ruleafter_build_file">rule:after_build_file</h3>
<h4 id="custompostcompilationscriptstoprocessonesourcefileatatime">Custom post-compilation scripts to process one source file at a time</h4>
<p>Similar to <a href="#ruleon_build_file">rule:on_build_file</a>, but the timing of this interface is called after compiling a source file.<br>Generally used to post-process some compiled object files.</p>
<h3 id="ruleafter_buildcmd_file">rule:after_buildcmd_file</h3>
<h4 id="customizethecompiledbatchscriptprocessonesourcefileatatime">Customize the compiled batch script, process one source file at a time</h4>
<p>Similar to the usage of <a href="#ruleon_buildcmd_file">rule:on_buildcmd_file</a>, but the time when this interface is called is after compiling a certain source file,<br>Generally used for post-processing some compiled object files.</p>
<h3 id="ruleafter_build_files">rule:after_build_files</h3>
<h4 id="customizethecompiledscripttoprocessmultiplesourcefilesatonce">Customize the compiled script to process multiple source files at once</h4>
<p>The usage is similar to <a href="#ruleon_build_files">rule:on_build_files</a>, but the time when this interface is called is after some source files are compiled,<br>Generally used for post-processing some compiled object files.</p>
<h3 id="ruleafter_buildcmd_files">rule:after_buildcmd_files</h3>
<h4 id="customizethecompiledbatchscripttoprocessmultiplesourcefilesatonce">Customize the compiled batch script to process multiple source files at once</h4>
<p>The usage is similar to <a href="#ruleon_buildcmd_files">rule:on_buildcmd_files</a>, but the time when this interface is called is after compiling some source files,<br>Generally used for post-processing some compiled object files.</p>
<h3 id="rule_end">rule_end</h3>
<h4 id="enddefinitionrules">End definition rules</h4>
<p>This is optional. If you want to manually end the rule definition, you can call it:</p>
<pre><code class="lang-lua">rule("test")
    -- ..
rule_end()
</code></pre>
</article>
</body>
</html>